home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3g / regcmp.z / regcmp
Encoding:
Text File  |  2002-10-03  |  11.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. rrrreeeeggggccccmmmmpppp((((3333GGGG))))                                                          rrrreeeeggggccccmmmmpppp((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _rrrr_eeee_gggg_cccc_mmmm_pppp, _rrrr_eeee_gggg_eeee_xxxx - compile and execute regular expression
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_llll_iiii_bbbb_gggg_eeee_nnnn_...._hhhh_>>>>
  13.  
  14.      _cccc_cccc [_f_l_a_g ...] _f_i_l_e ...  _----_llll_gggg_eeee_nnnn [_l_i_b_r_a_r_y ...]
  15.  
  16.      _cccc_hhhh_aaaa_rrrr _****_rrrr_eeee_gggg_cccc_mmmm_pppp _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_s_t_r_i_n_g_1 _[[[[_,,,, _cccc_hhhh_aaaa_rrrr _****_s_t_r_i_n_g_2_,,,, _...._...._...._]]]]_,,,,
  17.          _((((_cccc_hhhh_aaaa_rrrr _****_))))_0000_))))_;;;;
  18.  
  19.      _cccc_hhhh_aaaa_rrrr _****_rrrr_eeee_gggg_eeee_xxxx _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_r_e_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_s_u_b_j_e_c_t
  20.          _[[[[_,,,, _cccc_hhhh_aaaa_rrrr _****_r_e_t_0_,,,, _...._...._...._]]]]_))))_;;;;
  21.  
  22.      _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****___________llll_oooo_cccc_1111_;;;;
  23.  
  24. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  25.      _rrrr_eeee_gggg_cccc_mmmm_pppp compiles a regular expression (consisting of the concatenated
  26.      arguments) and returns a pointer to the compiled form.  _mmmm_aaaa_llll_llll_oooo_cccc(3C) is
  27.      used to create space for the compiled form.  It is the user's
  28.      responsibility to free unneeded space so allocated.  A _NNNN_UUUU_LLLL_LLLL return from
  29.      _rrrr_eeee_gggg_cccc_mmmm_pppp indicates an incorrect argument.  _rrrr_eeee_gggg_cccc_mmmm_pppp(1) has been written to
  30.      generally preclude the need for this routine at execution time.
  31.  
  32.      _rrrr_eeee_gggg_eeee_xxxx executes a compiled pattern against the subject string.  Additional
  33.      arguments are passed to receive values back.  _rrrr_eeee_gggg_eeee_xxxx returns _NNNN_UUUU_LLLL_LLLL on
  34.      failure or a pointer to the next unmatched character on success.  A
  35.      global character pointer ___________llll_oooo_cccc_1111 points to where the match began.  Note
  36.      that in the subject string the newline character (_\\\\_nnnn) is not considered a
  37.      delimiter, thus constructs such as anchoring work only on the basis of
  38.      the entire string, not any individual 'lines' within the string.  _rrrr_eeee_gggg_cccc_mmmm_pppp
  39.      and _rrrr_eeee_gggg_eeee_xxxx were mostly borrowed from the editor, _eeee_dddd(1); however, the
  40.      syntax and semantics have been changed slightly.  The following are the
  41.      valid symbols and associated meanings.
  42.  
  43.      _[[[[_]]]]_****_...._^^^^     These symbols retain their meaning in _eeee_dddd(1).
  44.  
  45.      _$$$$         Matches the end of the string; _\\\\_nnnn matches a newline.
  46.  
  47.      _----         Within brackets the minus means _t_h_r_o_u_g_h.  For example, _[[[[_aaaa_----_zzzz_]]]] is
  48.                equivalent to _[[[[_aaaa_bbbb_cccc_dddd_...._...._...._xxxx_yyyy_zzzz_]]]].  The _---- can appear as itself only if
  49.                used as the first or last character.  For example, the
  50.                character class expression _[[[[_]]]]_----_]]]] matches the characters _]]]] and _----.
  51.  
  52.      _++++         A regular expression followed by _++++ means _o_n_e _o_r _m_o_r_e _t_i_m_e_s.
  53.                For example, _[[[[_0000_----_9999_]]]]_++++ is equivalent to _[[[[_0000_----_9999_]]]]_[[[[_0000_----_9999_]]]]_****_....
  54.  
  55.      _{{{{_m_}}}} _{{{{_m,_}}}} _{{{{_m,_u_}}}}
  56.                Integer values enclosed in _{{{{_}}}} indicate the number of times the
  57.                preceding regular expression is to be applied.  The value _m is
  58.                the minimum number and _u is a number, less than 256, which is
  59.                the maximum.  If only _m is present (that is, _{{{{_m_}}}}), it indicates
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rrrreeeeggggccccmmmmpppp((((3333GGGG))))                                                          rrrreeeeggggccccmmmmpppp((((3333GGGG))))
  71.  
  72.  
  73.  
  74.                the exact number of times the regular expression is to be
  75.                applied.  The value _{{{{_m_,,,,_}}}} is analogous to _{{{{_m,_i_n_f_i_n_i_t_y_}}}}_....  The
  76.                plus (_++++) and star (_****) operations are equivalent to _{{{{_1111_,,,,_}}}} and
  77.                _{{{{_0000_,,,,_}}}} respectively.
  78.  
  79.      _(((( _...._...._.... _))))_$$$$_n The value of the enclosed regular expression is to be returned.
  80.                The value will be stored in the (_n+1)th argument following the
  81.                subject argument.  At most, ten enclosed regular expressions
  82.                are allowed.  _rrrr_eeee_gggg_eeee_xxxx makes its assignments unconditionally.
  83.  
  84.      _(((( _...._...._.... _))))   Parentheses are used for grouping.  An operator, for example,
  85.                _****, _++++, _{{{{_}}}}, can work on a single character or a regular
  86.                expression enclosed in parentheses.  For example, _((((_aaaa_****_((((_cccc_bbbb_++++_))))_****_))))_$$$$_0000.
  87.  
  88.      By necessity, all the above defined symbols are special.  They must,
  89.      therefore, be escaped with a _\\\\ (backslash) to be used as themselves.  In
  90.      some cases (parenthesis _((((_)))) and braces _{{{{_}}}}) this is exactly the opposite of
  91.      _eeee_dddd(1).
  92.  
  93. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  94.      The following example matches a leading newline in the subject string
  95.      pointed at by cursor.
  96.  
  97.           _cccc_hhhh_aaaa_rrrr _****_cccc_uuuu_rrrr_ssss_oooo_rrrr_,,,, _****_nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr_,,,, _****_pppp_tttt_rrrr_;;;;
  98.                _...._...._....
  99.           _nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr _==== _rrrr_eeee_gggg_eeee_xxxx_((((_((((_pppp_tttt_rrrr _==== _((((_cccc_hhhh_aaaa_rrrr _****_))))_rrrr_eeee_gggg_cccc_mmmm_pppp_((((_""""_^^^^_\\\\_nnnn_""""_,,,, _((((_cccc_hhhh_aaaa_rrrr _****_))))_0000_))))_))))_,,,, _cccc_uuuu_rrrr_ssss_oooo_rrrr_))))_;;;;
  100.           _ffff_rrrr_eeee_eeee_((((_pppp_tttt_rrrr_))))_;;;;
  101.  
  102.      The following example matches through the string _TTTT_eeee_ssss_tttt_iiii_nnnn_gggg_3333 and returns the
  103.      address of the character after the last matched character (the ``_4444'').
  104.      The string _TTTT_eeee_ssss_tttt_iiii_nnnn_gggg_3333 is copied to the character array _rrrr_eeee_tttt_0000.
  105.  
  106.           _cccc_hhhh_aaaa_rrrr _rrrr_eeee_tttt_0000_[[[[_9999_]]]]_;;;;
  107.           _cccc_hhhh_aaaa_rrrr _****_nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr_,,,, _****_nnnn_aaaa_mmmm_eeee_;;;;
  108.                _...._...._....
  109.           _nnnn_aaaa_mmmm_eeee _==== _rrrr_eeee_gggg_cccc_mmmm_pppp_((((_""""_((((_[[[[_AAAA_----_ZZZZ_aaaa_----_zzzz_]]]]_[[[[_AAAA_----_zzzz_aaaa_----_zzzz_0000_----_9999_]]]]_{{{{_0000_,,,,_7777_}}}}_))))_$$$$_0000_""""_,,,, _((((_cccc_hhhh_aaaa_rrrr _****_))))_0000_))))_;;;;
  110.           _nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr _==== _rrrr_eeee_gggg_eeee_xxxx_((((_nnnn_aaaa_mmmm_eeee_,,,, _""""_0000_1111_2222_TTTT_eeee_ssss_tttt_iiii_nnnn_gggg_3333_4444_5555_""""_,,,, _rrrr_eeee_tttt_0000_))))_;;;;
  111.  
  112.      The following example applies a precompiled regular expression in _ffff_iiii_llll_eeee_...._iiii
  113.      [see _rrrr_eeee_gggg_cccc_mmmm_pppp(1)] against _s_t_r_i_n_g.
  114.  
  115.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _""""_ffff_iiii_llll_eeee_...._iiii_""""
  116.           _cccc_hhhh_aaaa_rrrr _****_ssss_tttt_rrrr_iiii_nnnn_gggg_,,,, _****_nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr_;;;;
  117.                _...._...._....
  118.           _nnnn_eeee_wwww_cccc_uuuu_rrrr_ssss_oooo_rrrr _==== _rrrr_eeee_gggg_eeee_xxxx_((((_nnnn_aaaa_mmmm_eeee_,,,, _ssss_tttt_rrrr_iiii_nnnn_gggg_))))_;;;;
  119.  
  120. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  121.      _eeee_dddd(1), _rrrr_eeee_gggg_cccc_mmmm_pppp(1), _mmmm_aaaa_llll_llll_oooo_cccc(3C)
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. rrrreeeeggggccccmmmmpppp((((3333GGGG))))                                                          rrrreeeeggggccccmmmmpppp((((3333GGGG))))
  137.  
  138.  
  139.  
  140. NOTES
  141.      The user program may run out of memory if _rrrr_eeee_gggg_cccc_mmmm_pppp is called iteratively
  142.      without freeing the vectors no longer required.
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.